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Status of this Memo 


This document specifies an Internet standards track protocol for the 
Internet community, and requests discussion and suggestions for 


improvements. Please refer to the current edition of the "Internet 
Official Protocol Standards" (STD 1) for the standardization state 
and status of this protocol. Distribution of this memo is unlimited. 


Copyright Notice 
Copyright (C) The Internet Society (2004). All Rights Reserved. 
Abstract 


This document defines and describes the IntermediateResponse message, 
a general mechanism for defining single-request/multiple-response 
operations in Lightweight Directory Access Protocol (LDAP). The 
IntermediateResponse message is defined in such a way that the 
protocol behavior of existing LDAP operations is maintained. This 
message is intended to be used in conjunction with the LDAP 
ExtendedRequest and ExtendedResponse to define new single- 
request/multiple-response operations or in conjunction with a control 
when extending existing LDAP operations in a way that requires them 
to return intermediate response information. 
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Les 


Introduction 


The Lightweight Directory Access Protocol (LDAP), version 3 [RFC3377] 


is an extensible protocol. Extended operations ([RFC2251] Section 
4.12) are defined to allow for the addition of operations to LDAP, 
without requiring revisions of the protocol. Similarly, controls 


((RFC2251] Section 4.1.12) are defined to extend or modify the 
behavior of existing LDAP operations. 


LDAP is a client-request/server-response based protocol. With the 
exception of the search operation, the entire response to an 
operation request is returned in a single protocol data unit (i.e., 
LDAP message). While this single-request/single-response paradigm is 
sufficient for many operations (including all but one of those 
currently defined by [RFC3377]), both intuition and practical 
experience validate the notion that it is insufficient for others. 


For example, the LDAP delete operation could be extended via a 
subtree control to mean that an entire subtree is to be deleted. A 
subtree delete operation needs to return continuation references 
based upon subordinate knowledge information contained in the server 
so that the client can complete the operation. Returning references 
as they are found, instead of with the final result, allows the 
client to perform the operation more efficiently because it does not 
have to wait for the final result to get this continuation reference 
information. 


Similarly, an engineer might choose to design the subtree delete 
operation as an extended operation of its own rather than using a 
subtree control in conjunction with the delete operation. Once 
again, the same continuation reference information is needed by the 
client to complete the operation, and sending the continuation 
references as they are found would allow the client to perform the 
operation more efficiently. 


Operations that are completed in stages or that progress through 
various states as they are completed might want to send intermediate 
responses to the client, thereby informing it of the status of the 
operation. For example, an LDAP implementation might define an 
extended operation to create a new replica of an administrative area 


on a server, and the operation is completed in three stages: (1) 
begin creation of replica, (2) send replica data to server, (3) 
replica creation complete. Intermediate messages might be sent from 


the server to the client at the beginning of each stage with the 
final response for the extended operation being sent after stage (3) 
is complete. 
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As LDAP [RFC3377] is currently defined, there is no general LDAP 
message type that can be used to return intermediate results. A 
single, reusable LDAP message for carrying intermediate response 
information is desired to avoid repeated modification of the 
protocol. Although the ExtendedResponse message is defined in LDAP, 
it is defined to be the one and only response message to an 
ExtendedRequest message ([RFC2251] Section 4.12), for unsolicited 
notifications ([RFC2251] Section 4.4), and to return intermediate 
responses for the search operation ([RFC3377] Section 4.5.2, also see 
Section 5 below). The adaptation of ExtendedResponse as a general 
intermediate response mechanism would be problematic. In particular, 
existing APIs would likely have to be redesigned. It is believed 
(based upon operational experience) that the addition of a new 
message to carry intermediate result information is easier to 
implement and is less likely to cause interoperability problems with 
existing deployed implementations. 


This document defines and describes the LDAP IntermediateResponse 
message. This message is intended to be used in conjunction with 
ExtendedRequest and ExtendedResponse to define new single- 
request/multiple-response operations or in conjunction with a control 
when extending existing LDAP operations in a way that requires them 
to return intermediate response information. 


It is intended that the definitions and descriptions of extended 
operations and controls using the IntermediateResponse message will 
define the circumstances in which an IntermediateResponse message can 
be sent by a server and the associated meaning of the 
IntermediateResponse message sent in a particular circumstance. 
Similarly, it is intended that clients will explicitly solicit 
IntermediateResponse messages by issuing operations that specifically 
call for their return. 


The LDAP Content Sync Operation [ZEILENGA] demonstrates one use of 
LDAP Intermediate Response messages. 


2. Conventions used in this document 


The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", “SHALL NOT", 
"SHOULD", “SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 
document are to be interpreted as described in [RFC2119]. 


The term "request control" is used to describe a control that is 
included in an LDAP request message sent from an LDAP client to an 
LDAP server. 
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3- 


3: 


The IntermediateResponse Message 


This document extends the protocolOp CHOICE of LDAPMessage ([RFC2251] 
Section 4.1.1) to include the field: 


intermediateResponse IntermediateResponse 


where IntermediateResponse is defined as: 


IntermediateResponse ::= [APPLICATION 25] SEQUENCE { 
responseName [0] LDAPOID OPTIONAL, 
responseValue [1] OCTET STRING OPTIONAL } 


IntermediateResponse messages SHALL NOT be returned to the client 
unless the client issues a request that specifically solicits their 
return. This document defines two forms of solicitation: extended 
operation and request control. 


Although the responseName and responseValue are optional in some 
circumstances, IntermediateResponse messages usually have a 
predefined responseName and a responseValue. The value of the 
responseName (if present), the syntax of the responseValue (if 
present) and the semantics associated with a particular 
IntermediateResponse message MUST be specified in documents 
describing the extended operation or request control that uses them. 
Sections 3.1 and 3.2 describe additional requirements for the 
inclusion of responseName and responseValue in IntermediateResponse 
messages. 


1. Usage with LDAP ExtendedRequest and ExtendedResponse 


A single-request/multiple-response operation may be defined using a 
single ExtendedRequest message to solicit zero or more 
IntermediateResponse messages, of one or more kinds, followed by an 
ExtendedResponse message. 


An extended operation that defines the return of multiple kinds of 
IntermediateResponse messages MUST provide and document a mechanism 
for the client to distinguish the kind of IntermediateResponse 
message being sent. This SHALL be accomplished by using different 
responseName values for each type of IntermediateResponse message 
associated with the extended operation or by including identifying 
information in the responseValue of each type of IntermediateResponse 
message associated with the extended operation. 
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3.2. Usage with LDAP Request Controls 


Any LDAP operation may be extended by the addition of one or more 
controls ([RFC2251] Section 4.1.12). A control’s semantics may 
include the return of zero or more IntermediateResponse messages 
prior to returning the final result code for the operation. One or 
more kinds of IntermediateResponse messages may be sent in response 
to a request control. 


All IntermediateResponse messages associated with request controls 
SHALL include a responseName. This requirement ensures that the 
client can correctly identify the source of IntermediateResponse 
messages when: 


a) two or more controls using IntermediateResponse messages are 
included in a request for any LDAP operation or 


b) one or more controls using IntermediateResponse messages are 
included in a request with an LDAP extended operation that uses 
IntermediateResponse messages. 


A request control that defines the return of multiple kinds of 
IntermediateResponse messages MUST provide and document a mechanism 
for the client to distinguish the kind of IntermediateResponse 
message being sent. This SHALL be accomplished by using different 
responseName values for each type of IntermediateResponse message 
associated with the request control or by including identifying 
information in the responseValue of each type of IntermediateResponse 
message associated with the request control. 


4. Advertising Support for IntermediateResponse Messages 


Because IntermediateResponse messages are associated with extended 
operations or controls and LDAP provides a means for advertising the 
extended operations and controls supported by a server (using the 
supportedExtension ([RFC2252] Section 5.2.3) and supportedControl 
([RFC2252] Section 5.2.4) attributes of the root DSE), there is no 
need for a separate means of advertising support for intermediate 
response messages. 


5. Use of IntermediateResponse and ExtendedResponse with Search 


It is noted that ExtendedResponse messages may be sent in response to 
LDAP search operations with controls ([RFC2251] Section 4.5.2). This 
use of ExtendedResponse messages SHOULD be viewed as deprecated, in 
favor of use of the IntermediateResponse messages. 
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6. Security Considerations 
This document describes an enhancement to LDAP. All security 
considerations of [RFC3377] apply to this document; however, it does 
not introduce any new security considerations to LDAP. 
Security considerations specific to each extension using this 
protocol mechanism shall be discussed in the technical specification 
detailing the extension. 
7. IANA Considerations 
Registration of the following value has been completed [RFC3383]. 
7.1. LDAP Message Type 
The IANA has registered an LDAP Message Type (25) to identify the 


LDAP IntermediateResponse message as defined in section 3 of this 
document. 


The following registration template is suggested: 


Subject: Request for LDAP Message Type Registration 
Person & email address to contact for further information: 
Roger Harrison <roger_harrison@novell.com> 
Specification: RFC3771 
Author/Change Controller: IESG 
Comments: Identifies the LDAP IntermediateResponse Message 
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11. Full Copyright Statement 


Copyright (C) The Internet Society (2004). This document is subject 
to the rights, licenses and restrictions contained in BCP 78, and 
except as set forth therein, the authors retain all their rights. 


This document and the information contained herein are provided on an 
"AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 
OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET 
ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, 
INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE 
INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 
WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 


Intellectual Property 


The IETF takes no position regarding the validity or scope of any 
Intellectual Property Rights or other rights that might be claimed to 
pertain to the implementation or use of the technology described in 
this document or the extent to which any license under such rights 
might or might not be available; nor does it represent that it has 
made any independent effort to identify any such rights. Information 
on the procedures with respect to rights in RFC documents can be 
found in BCP 78 and BCP 79. 


Copies of IPR disclosures made to the IETF Secretariat and any 
assurances of licenses to be made available, or the result of an 
attempt made to obtain a general license or permission for the use of 
such proprietary rights by implementers or users of this 
specification can be obtained from the IETF on-line IPR repository at 
http://www.ietf.org/ipr. 


The IETF invites any interested party to bring to its attention any 
copyrights, patents or patent applications, or other proprietary 
rights that may cover technology that may be required to implement 
this standard. Please address the information to the IETF at ietf- 
ipr@ietf.org. 
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